8. The Service Layer

Services in Grails are seen as the place to put the majority of the logic in your application, leaving controllers responsible for handling request flow via redirects and so on.

Creating a Service

You can create a Grails service by running the create-service command from the root of your project in a terminal window:

grails create-service helloworld.simple

If no package is specified with the create-service script, Grails automatically uses the application name as the package name.

The above example will create a service at the location grails-app/services/helloworld/SimpleService.groovy. A service's name ends with the convention Service, other than that a service is a plain Groovy class:

package helloworld
class SimpleService {
}

8.1 Declarative Transactions

Default Declarative Transactions

Services are typically involved with co-ordinating logic between domain classes, and hence often involved with persistence that spans large operations. Given the nature of services they frequently require transactional behaviour. You can of course use programmatic transactions with the withTransaction method, however this is repetitive and doesn't fully leverage the power of Spring's underlying transaction abstraction.

Services allow the enablement of transaction demarcation, which is essentially a declarative way of saying all methods within this service are to be made transactional. All services have transaction demarcation enabled by default - to disable it, simply set the transactional property to false:

class CountryService {
    static transactional = false
}

You may also set this property to true in case the default changes in the future, or simply to make it clear that the service is intentionally transactional.

Warning: dependency injection is the only way that declarative transactions work. You will not get a transactional service if you use the new operator such as new BookService()

The result is that all methods are wrapped in a transaction and automatic rollback occurs if any of those methods throws a runtime exception, i.e. one that extends RuntimeException. The propagation level of the transaction is by default set to PROPAGATION_REQUIRED.

Checked exceptions do not have any effect on the transaction, i.e. the transaction is not automatically rolled back. This is the default Spring behaviour and it's important to understand the distinction between checked and unchecked (runtime) exceptions.

Custom Transaction Configuration

Grails also fully supports Spring's Transactional annotation for cases where you need more fine-grained control over transactions at a per-method level or need specify an alternative propagation level:

import org.springframework.transaction.annotation.*
class BookService {
	@Transactional(readOnly = true) 
	def listBooks() { Book.list() }
	@Transactional def updateBook() { 
		// � 
	}
}

For more information refer to the section of the Spring user guide on Using @Transactional.

Unlike Spring you do not need any prior configuration to use Transactional, just specify the annotation as needed and Grails will pick them up automatically.

Annotating a service method with Transactional disables the default Grails transactional behavior for that service and all other transactional methods need to be annotated as well.

8.1.1 Transactions Rollback and the Session

Understanding Transactions and the Hibernate Session

When using transactions there are important considerations you need to take into account with regards to how the underlying persistence session is handled by Hibernate. When a transaction is rolled back the Hibernate session used by GORM is cleared. This means any objects within the session become detached and accessing collections could lead to a LazyInitializationException.

To understand why it is important that the Hibernate session is cleared. Consider the following example:

class Author {
	String name
	int age
	static hasMany = [books:Book]
}

If you were to save 2 authors using consecutive transactions as follows:

Author.withTransaction { status ->
   new Author(name:"Stephen King", age:40).save()
   status.setRollbackOnly()
}
Author.withTransaction { status ->
   new Author(name:"Stephen King", age:40).save()
}

Only the last author would be saved since the first transaction rolls back the author save by clearing the Hibernate session. If the Hibernate session were not cleared then both author instance would be persisted and it would lead to very unexpected results.

It can, however, be frustrating to get LazyInitializationException due to the session being cleared.

For example, consider the following example:

class AuthorService {
	static transactional = true
	void updateAge(id, int age) {
		def author = Author.get(id)
		author.age = age
		if(author.age > 100) {
			throw new AuthorException("too old", author)
		}
	}
}

class AuthorController {
	AuthorService authorService
	def updateAge() {
		try {
			authorService.updateAge(params.id, params.int("age"))
		}
		catch(e) {
			render "Author books ${e.author.books}"
		}
	}
}

In the above example the transaction will be rolled back if the Author's age exceeds 100 by throwing an AuthorException. The AuthorException references the author but when the books association is accessed a LazyInitializationException will be thrown because the underlying Hibernate session has been cleared.

To solve this problem you have a number of options. One option is to ensure you query eagerly to get the data you are going to need:

class AuthorService {
	...	
	void updateAge(id, int age) {
		def author = Author.findById(id, [fetch:[books:"eager"]])
		...

In this example the books association will be queried when retrieving the Author.

This is the optimal solution as it requires fewer queries then the following suggested solutions.

Another, alternative solution is to redirect the request after a transaction rollback:

class AuthorController {
	AuthorService authorService
	def updateAge() {
		try {
			authorService.updateAge(params.id, params.int("age"))
		}
		catch(e) {
			flash.message "Can't update age"
			redirect action:"show", id:params.id
		}
	}
}

In this case a new request will deal with retrieving the Author again. And, finally a third solution is to retrieve the data for the Author again to make sure the session remains in the correct state:

class AuthorController {
	AuthorService authorService
	def updateAge() {
		try {
			authorService.updateAge(params.id, params.int("age"))
		}
		catch(e) {
			def author = Author.read(params.id)
			render "Author books ${author.books}"
		}
	}
}

Validation Errors and Rollback

A common use case is rollback a transaction if there are validation errors. For example consider this service:

import grails.validation.**
class AuthorService {
	static transactional = true
	void updateAge(id, int age) {
		def author = Author.get(id)
		author.age = age
		if(!age.validate()) {
			throw new ValidationException("Author is not valid", author.errors)
		}
	}
}

If you need to re-render the same view that a transaction was rolled back in you can re-associate the errors with a refreshed instance before rendering:

class AuthorController {
	AuthorService authorService
	def updateAge() {
		try {
			authorService.updateAge(params.id, params.int("age"))
		}
		catch(ValidationException e) {
			def author = Author.read(params.id)
			author.errors = e
			render view:"edit", model: [author:author]
		}
	}
}

8.2 Scoped Services

You can change this behaviour by placing a service in a particular scope. The supported scopes are:

• prototype - A new service is created every time it is injected into another class
• request - A new service will be created per request
• flash - A new service will be created for the current and next request only
• flow - In web flows the service will exist for the scope of the flow
• conversation - In web flows the service will exist for the scope of the conversation. ie a root flow and its sub flows
• session - A service is created for the scope of a user session
• singleton (default) - Only one instance of the service ever exists

If your service is flash, flow or conversation scoped it will need to implement java.io.Serializable and can only be used in the context of a Web Flow

To enable one of the scopes, add a static scope property to your class whose value is one of the above:

static scope = "flow"

8.3 Dependency Injection and Services

Dependency Injection Basics

A key aspect of Grails services is the ability to take advantage of the Spring Framework's dependency injection capability. Grails supports "dependency injection by convention". In other words, you can use the property name representation of the class name of a service, to automatically inject them into controllers, tag libraries, and so on.

As an example, given a service called BookService, if you place a property called bookService within a controller as follows:

class BookController {
   def bookService
   …
}

In this case, the Spring container will automatically inject an instance of that service based on its configured scope. All dependency injection is done by name. You can also specify the type as follows:

class AuthorService {
	BookService bookService
}

NOTE: Normally the property name is generated by lower casing the first letter of the type. For example, an instance of the BookService class would map to a property named bookService.

To be consistent with standard JavaBean convetions, if the first 2 letters of the class name are upper case, the property name is the same as the class name. For example, an instance of the MYhelperService class would map to a property named MYhelperService.

See section 8.8 of the JavaBean specification for more information on de-capitalization rules.

Dependency Injection and Services

You can inject services in other services with the same technique. Say you had an AuthorService that needed to use the BookService, declaring the AuthorService as follows would allow that:

class AuthorService {
	def bookService
}

Dependency Injection and Domain Classes

You can even inject services into domain classes, which can aid in the development of rich domain models:

class Book {	
	…
	def bookService
	def buyBook() {
		bookService.buyBook(this)
	}
}

8.4 Using Services from Java

class BookService {
	void buyBook(Book book) {
		// logic
	}
}

However, this can be rectified by placing this class in a package, by moving the class into a sub directory such as grails-app/services/bookstore and then modifying the package declaration:

package bookstore
class BookService {
	void buyBook(Book book) {
		// logic
	}
}

An alternative to packages is to instead have an interface within a package that the service implements:

package bookstore;
interface BookStore {
	void buyBook(Book book);
}

And then the service:

class BookService implements bookstore.BookStore {
	void buyBook(Book b) {
		// logic
	}
}

This latter technique is arguably cleaner, as the Java side only has a reference to the interface and not to the implementation class. Either way, the goal of this exercise to enable Java to statically resolve the class (or interface) to use, at compile time. Now that this is done you can create a Java class within the src/java package, and provide a setter that uses the type and the name of the bean in Spring:

package bookstore;
// note: this is Java class
public class BookConsumer {
	private BookStore store;
	public void setBookStore(BookStore storeInstance) {
		this.store = storeInstance;
	}	
	…
}

Once this is done you can configure the Java class as a Spring bean in grails-app/conf/spring/resources.xml (For more information one this see the section on Grails and Spring):

<bean id="bookConsumer" class="bookstore.BookConsumer">
	<property name="bookStore" ref="bookService" />
</bean>